LESSON 4
AN INTRODUCTION TO THE MAGIC RAM
Version 4.0

An Overview Of Memory For The Bally/Astrocade Computer

The Bally/Astrocade computer motherboard provides 8KB of ROM addressed 0000-1FFFH. Half of this ROM addressed 0000-0FFFH contains 64 routines/subroutines which are accessible by the execution of a User Programmer Interface (UPI) initiated by a Z80 restart instruction (RST 38H, opcode FFH). There is also a power-up routine to set up a power-on menu for the selection and execution of four onboard programs Gunfight, Checkmate, Scribbling and Calculator, which are located in the other half of the 8KB ROM addressed 1000-1FFFH. The power-up routine includes a sentry to check for up to 8KB of ROM addressed 2000-3FFFH in the form of a plastic cartridge which can be inserted into a cassette-like connector/holder. This plastic cartridge may be referred to as a cassette, cassette ROM or a Videocade. The cassette ROM can be programmed to utilize and extend the power-on menu or use a programmed custom graphics startup display.

There is 4KB of screen RAM addressed 4000-4FFFH. A 50 pin expansion at the rear of the computer allows connection to up to an additional 44KB of directly addressible User RAM at 5000-FFFFH or for connection to other types of add-ons. The expansion connection is made using a 50 pin ribbon cable connector.

The Nutting Manual system description, pages 82 and 83, provides a brief description and illustration of the low-resolution Bally/Astrocade computer memory map.

Magic RAM

The Bally/Astrocade computer utilizes a Zilog Z80 microprocessor (CPU) to perform various tasks and execute program instructions. The Z80 instruction set has ample amount of bit manipulation instructions to write graphics to the screen RAM display. However, this means of writing graphics is not necessary, because the Bally/Astrocade computer's motherboard includes graphic hardware to manipulate screen bits or pixels faster and with less effort.

Instead of writing data to screen RAM for pixel manipulation, data can be written to 4KB of ROM addressed 0000-0FFFH. This particular write to ROM activates the bit manipulation hardware and is referred to as writing to Magic RAM. The hardware includes 2 programmable output registers called the Magic Register (output port 0CH) and the Expand Register (output port 19H) which tell the hardware how to manipulate the written bits (bytes). Note Magic RAM is 4KB addressed 0000-0FFFH and screen RAM is also 4KB, but is addressed 4000-4FFFH. When you write to Magic RAM, the hardware adds 16KB, so to speak, to the Magic RAM address so the memory writes actually end up in screen RAM. For example, a magic write to address 0000H ends up in screen RAM address 4000H. A magic write to address 0001H ends up in screen RAM address 4001H and so on. The last Magic RAM address is 0FFFH. A magic write to that address will end up at RAM address 4FFFH. So, the hardware is essentially setting the memory address bit A14 to logic 1 so the write ends up in screen RAM. The programmer must tell the hardware how to manipulate the data written to Magic RAM using the Magic Register for the desired magic function(s) request and also the Expand Register, if the magic function request includes an expansion request.

The programmer must also provide a machine language routine specifically instructing the Magic RAM hardware, when writing graphic patterns or characters. Fortunately, the ROM at 0000-0FFFH includes graphic display subroutines to support the graphics hardware and so, it is simply a matter of knowing how to set up the appropriate Z80 registers for use with the subroutine and then access (call) the subroutine using the UPI. When the subroutine is set up and called correctly, the subroutine tells the graphics hardware what to do. Using the ROM UPI to call an onboard ROM subroutine only takes a few program bytes. However, additional bytes may be required for certain data blocks or tables, for example, to be used by the subroutine. See the onboard subroutine details for specifics. The programmer also has the option to provide a custom machine language graphics routine to be called directly by the Z80 instead of using the UPI. This option will provide maximum execution speed (no UPI processing delay) to push the Z80 to its graphic display limits.

The graphics hardware provides the following magic functions:
plop the write into screen RAM
OR logical the write with screen RAM
XOR logical the write with screen RAM
shift the write 0,1,2 or 3 pixels
flop the write into screen RAM
expand the write to 2 pixel colors in screen RAM
rotate a 4x4 pixel graphic pattern in screen RAM

The Nutting Manual system description, pages 94 thru 100, provides info on the Magic and Expand Registers and the various magic functions. Note there is an error on top of page 94. The magic system (RAM) is enabled when data is written to a memory location (X) from 0 to 4K (not 16K). See the top of the illustration on page 83. Magic RAM is addressed 0000-0FFFH (4KB). Contrary to the NM statement regarding the magic rotator function on page 98, the rotator function IS operable in the low-res (consumer) mode. However, there is no software support in ROM for the magic rotator function. The user must provide the necessary ML routine to implement the rotator function. Finally, if the magic "OR" bit 4 is NOT set and also the magic "XOR" bit 5 is NOT set, within the Magic Register, then the write is "plopped" into screen RAM. A plop write simply writes over the current byte in screen RAM.

Lessons Introducing The Magic RAM

The next few lessons will utilize the Magic RAM using subroutines called directly by the Z80. The calling of onboard UPI Magic RAM graphic subroutines will be presented in lessons a little later in this series.

Using a direct subroutine call in these next few lessons will allow the reader to see how graphic patterns are written (displayed) in screen RAM. Some of these write routines will be variations of subroutines that already exist in ROM.

In most cases, even though the UPI takes time to process a UPI subroutine call, the processing delay does not really affect graphic display performance. But, a programmer some day may have a graphics application which requires maximum execution speed to write and move graphics that are near the Z80's limit of execution speed. In this case, the programmer may not need to create a routine from scratch. A programmer can use the NM's detailed ROM subroutines within the 0000-0FFFH ROM code listing as a guide for writing and executing custom direct call graphic or vector subroutines thus avoiding any UPI processing delay. The next few lessons will also show that custom direct call graphic subroutines can be written to utilize the Magic RAM hardware.

Introduction To The Magic Pixel Shift Function

Example 4-1 below will examine how the Magic RAM can be used to shift horizontally a magic write 0,1,2 or 3 pixels.

EXAMPLE 4-1

Program Description

Set up program and leave room to run experiments to test the magic pixel shift function.
Write the reference byte FFH (solid green) at RAM address 4014H.
Begin experiments with the shifter byte located 2 RAM lines right below the reference byte.

Comment:
Since the shifter byte will be right below the reference byte by 2 RAM lines, just add 80 bytes to the reference byte address 4014H to determine the address of the shifter byte.

14H = 20, 20 + 80 = 100 = 64H

So, the address of the shifter byte = 4064H. However, you MUST write the shifter byte to the Magic RAM address 0064H.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Example Program 4-1

4E10H	CD 47 23	CALL CLEAR		use MLM Clear screen sub

	3E FF		LD A,FFH		A = color value = 11 11 11 11 = solid green
	32 14 40	LD (4014H),A	Write the reference byte

SET UP MAGIC REGISTER

4E18H	3E 00		LD A,MREG		A = Magic Reg value request = 00H
						begin with zero shift, plop write
	D3 0C		OUT (Magic),A	set up magic function request
						output request to Magic Reg port 0CH
						bits 1-0 shift 0,1,2 or 3 pixels
						     4   or write
						     5   xor write
							   plop write bits 4=5=0
						     6   flop write
						see NM, system description, page 94

WRITE THE SHIFTER BYTES TO MAGIC RAM

4E1CH	3E 4E		LD A,0100 1110	A = 1st shifter byte to write
						01  00  11  10
						wht blk grn red

4E1EH	32 64 00	LD (0064H),A	write the 1st shifter byte to Magic RAM

4E21H	00 00		NOPs			leave room for 2nd shifter byte
4E23H	00 00 00	NOPs

4E26H	00		NOP			leave room for shifter clear byte
4E27H 00 00 00	NOPs

4E2AH	C9		RET			return to MLM

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Run the above program.
You should see a solid green reference byte on the top RAM line about midway on the screen.
You should also see the shifter byte 2 lines directly below the green reference byte. The pixel colors in the shifter byte should be left to right:
wht blk grn red.

Experiments

For each experiment below, make the change in the program as indicated, then call the program at 4E10H and note the change in the shifter byte(s).

Experiment 1
Shift the byte written to Magic RAM by one pixel.

4E18H 3E 01		LD A,MREG		A = Magic Reg value request = 01H
						shift byte 1 pixel to the right,
						plop write
Outcome:
The shifter byte pixels should now be shifted right one pixel as shown below.

blk wht blk grn

Notes:
Pixel 3, the left most pixel, is set to pixel color 00 = blk.
The previous red pixel on the right disappears.
Reference the shifter illustration in NM sys desc, page 97.

Experiment 2
Write a shifter clear byte 00H to the right of the shifter byte at the Magic RAM address 0064H so the red pixel DOES shift into the next byte. The shifter clear byte must be written to the Magic RAM address 0065H.

4E26H	AF		XOR A			A = 0 = shifter clear byte
						the XOR A instruction zeros reg A
4E27H	32 65 00	LD (0065H),A	write the shifter clear byte,
						Clear the final shifter byte in this line

Outcome:
The red pixel should now appear in the second shifter byte at 4065H in the pixel 3 location (the left most pixel in the byte).

grn grn grn grn

blk wht blk grn red
byte 1          byte 2

Important Note:
Any time you write a line of bytes to the Magic RAM, you MUST finish that line with a shifter clear byte, so that the pixels at the end of the line will shift  into the final clear byte.

Experiment 3
Write a 2nd shifter byte to the right of the 1st shifter byte.
Use pixel colors for the 2nd shifter byte as:
01  11  01  11
wht grn wht grn

Don't forget to write the final clear byte on this line to the right of the 2nd shifter byte.
Keep the shift amount the same as Experiment 2, i.e. shift write one pixel.

4E21H	3E 77		LD A,0111 0111	A = 2nd shifter byte to write
						    01  11  01  11
						    wht grn wht grn
4E23H	32 65 00	LD (0065H),A	write 2nd shifter byte to Magic RAM

4E26H	AF		XOR A			A = 0 = Clear final (3rd) byte
4E27H	32 66 00	LD (0066H),A	write final clear byte to Magic RAM

Outcome:
The pixel shift below the solid green reference byte should now look like:

Solid grn reference byte	grn grn grn grn

3 byte magic write       	blk wht blk grn red wht grn wht grn
with 1 pixel shift		byte 1          byte 2          byte 3

Experiment 4
Shift magic bytes written in Experiment 3 by two pixels.

4E18H	3E 02		LD A,MREG	A = Magic Reg value request = 02H
					shift bytes 2 pixels, plop write

Outcome:
grn grn grn grn

blk blk wht blk grn red wht grn wht grn
byte 1          byte 2          byte 3

Experiment 5
Shift magic bytes written in Experiment 3 by three pixels.

4E18H	3E 03		LD A,MREG	A = Magic Reg value request = 03H
					shift bytes 3 pixels, plop write

Outcome:
grn grn grn grn

blk blk blk wht blk grn red wht grn wht grn
byte 1          byte 2          byte 3

Introduction To The Magic Flop Function

Restore the Example Program 4-1 to its ORIGINAL listing including the 9 NOP instructions.

Run this original program again.
You should see the grn reference byte and the shifter byte as indicated below.

grn grn grn grn

wht blk grn red

Push MLM's LIST button once so you won't "eat up" the reference and shifter bytes.

Now, change the program as indicated below to flop the shifter byte.

4E18H	3E 40		LD A,MREG	A = Magic Reg value request = 0100 0000 = 40H
                                  flop the byte, plop write

After you make this change, run the program again and watch the pixels flop as shown below.

grn grn grn grn

red grn blk wht

Reference again NM sys desc, page 97, for a flopped byte.

Experiment 6
Shift flopped byte written to Magic RAM by one pixel.
Flopped bytes shift to the LEFT.
Write the shifter clear byte 00H to the LEFT of the shifter byte.
The clear byte must be written to the Magic RAM address 0063H.

Make the changes to the program as indicated below.

4E18H	3E 41		LD A,MREG	      A = Magic Reg value request = 0100 0001
						    flop it, shift 1 pixel, plop write

4E26H AF		XOR A			A = 0 = shift clear byte
4E27H	32 63 00	LD (0063H),A	write the shifter clear byte,
						clear the final shifter byte in this line

After you make the changes, run the program again.
You should see the shifter byte flopped and shifted left by one pixel.

    grn grn grn grn
red grn blk wht blk

Exercises

Write the 2nd shifter byte to Magic RAM address 0063H and the final clear byte to 0062H using Experiment 3 as a guide. Keep the shift amount of one pixel like you did in Experiment 6. See if you can run your program and get it to flop 2 bytes shifting them to the left by one pixel.

Two more experiments you can try is to change the Magic Register value request at 4E19H to:

Flop and shift to the left 2 pixels, 4E19H = 42H,
Flop and shift to the left 3 pixels, 4E19H = 43H.

Introduction To The Magic XOR Logical Function

The magic XOR logical function is useful as a blanking function when moving graphic patterns around the screen. You can use this function to write a graphic pattern to Magic RAM. If you write the graphic pattern a 2nd time at the exact same magic location using the same magic XOR function, then the pattern on the screen will be blanked.

A truth table for a XOR logical operation is shown below.

M | S	| M XOR S
  |   |
0 | 0 |    0
0 | 1 |    1
1 | 0 |    1
1 | 1 |    0

Think of the M column as the bit being written to Magic RAM and the S column as the respective bit currently in screen RAM. The "M XOR S" column is the outcome of the XOR logical function performed with the M bit and the S bit.

As the truth table indicates, when both bits M and S are 1, the outcome M XOR S is zero (cleared, blanked). The same outcome occurs if both bits M and S are 0. So, a graphic pattern in screen RAM can be blanked, if you XOR write an identical pattern at the exact location of the current pattern in screen RAM.

An example program using the magic XOR logical function during motion will be included in an upcoming lesson called "Move Pattern". 

EXAMPLE 4-2

Program Description

Set up the Magic Register to XOR logical a byte into screen address 4014H.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Example Program 4-2

SET UP MAGIC REGISTER
4E10H	3E 20		LD A,MREG		A = Magic Reg value request
						  = 0010 0000 = 20H
						  XOR logical write
	D3 0C		OUT (Magic),A	set up magic function request
						output request to Magic Reg port 0CH

WRITE BYTE TO MAGIC RAM

4E14H	3E 4E		LD A,0100 1110	A = byte to write
						  = 01  00  11  10
						    wht blk grn red
	32 14 00	LD (0014H),A	write byte to Magic RAM address at 0014H
4E19H	C9		RET			return to MLM

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Enter Example Program 4-2.
Clear the MLM screen by entering 2347 and pressing the CALL button.
Now, run the program. 
You will see a byte written at the top line on the screen near the middle of the line with the pixel colors from left to right:

wht blk grn red

Now, press the MLM LIST button once, then run the same program a 2nd time.
Note that the byte written on the top line has been blanked (erased).
If you run the program a 3rd time, the Magic byte will appear again.
You can just keep writing and blanking this byte.

Introduction To The Magic OR Logical Function

The magic OR logical function is useful when you would like to move a graphic pattern so it visually appears to move behind another graphic pattern, for example, a plane flying behind a cloud.

A truth table for an OR logical operation is shown below.

M | S | M OR S
  |   |
0 | 0 |   0
0 | 1 |   1
1 | 0 |   1
1 | 1 |   1

Think of the M column as the bit being written to Magic RAM and the S column as the respective bit currently in screen RAM. The "M OR S" column is the outcome of the OR logical function performed with the M bit and the S bit.

As the truth table indicates, the only time the outcome of the OR operation results in zero is when BOTH the bit written to Magic RAM and the respective bit currently in screen RAM are zero.

Note the case when a bit in screen RAM is currently 1. The bit written to Magic RAM can be either 0 or 1 and the outcome will remain at 1. So, if say a cloud is displayed with a pixel 11 color, any logical OR operation on the cloud will not affect the cloud's display. So, you can move a graphic plane pattern into the cloud pattern and it will look like the plane is flying behind the cloud.

An example program using the magic OR logical function during motion will be included in an upcoming lesson called "Move Pattern". 

EXAMPLE 4-3

Program Description

Write a solid green byte FFH at screen RAM location 4014H.
This byte will represent a foreground graphic pattern.
Write 2 bytes using the magic OR logical function at Magic RAM addresses 0013 and 0014H with the pixel colors:

wht blk grn red   wht red wht red
byte 1		byte 2

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Example Program 4-3

4E10H	3E FF		LD A,FFH		A = color value = solid grn = 1111 1111
	32 14 40	LD (4014H),A	write the foreground byte

SET UP MAGIC REGISTER

4E15H	3E 10		LD A,MREG		A = Magic Reg value request = 10H
						begin with zero shift, OR write
	D3 0C		OUT (Magic),A	set up magic function request
						output request to Magic Reg port 0CH

WRITE THE BACKGROUND PATTERN BYTES TO MAGIC RAM

4E19H	3E 4E 	LD A,0100 1110	A = 1st background byte to write
						  = 01  00  11  10
						    wht blk grn red
	32 13 00	LD (0013H),A	write the 1st byte to Magic RAM

	3E 66		LD A,0110 0110	A = 2nd background byte to write
						  = 01  10  01  10
						    wht red wht red
4E20H	32 14 00	LD (0014H),A	write 2nd byte to Magic RAM

	AF		XOR AF		A = 0 = final clear byte
	32 15 00	LD (0015H),A	write final clear byte to Magic RAM
4E27H	C9		RET			return to MLM

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Enter Example Program 4-3.
Clear the MLM screen by entering 2347 and pressing the CALL button.
Now, run the program.
You will see the 1st background byte to the left of the solid green byte.

wht blk grn red grn grn grn grn

The 2nd background byte, in your imagination, is behind the solid green byte.
Now, run the program 3 more times, each time changing the shift amount in the Magic Register 1, 2 and 3 pixels.
So, each time you run the program again, change the Magic Register request byte in 4E16H to 11, 12 and 13H respectively.
Don't forget to clear the screen before you run the program, so the previous OR logical write is erased.
Each time you run the program again, you will see a pixel from the 2nd background byte appearing on the right side of the solid green byte, giving the impression that the 2 background bytes are moving behind the solid green byte.

Introduction To The:
Magic Expand Function
Magic Rotator Function

Introductions to these 2 magic functions will be presented soon in separate lessons in this series. Look for these 2 intro lessons labeled as:

Custom Magic Expand
Custom Magic Rotator

End of the Lesson 4 document
An Introduction To The Magic Ram
MCM Design
August 2019